
\chapter{User interface}

\label{chapter:user}

This chapter describes the user interface to the {\bf T} system, which
is the current implementation of the {\bf T} language.  Also part of
the user interface are the various debugging facilities, which are
described in chapter \ref{chapter:debug}.

The features described in this chapter are highly volatile and
implementation-dependent.

\section{Invoking {\bf T}}


To invoke a {\bf T} system, one typically gives a command to the system
command processor, as appropriate to the operating system and installation.
For example, under Aegis, the following interaction might take place:
\begin{codexenv}
\$ t \\
524280 bytes per heap, 131071 bytes reserved \\
T 3.1 (5) MC68000/UNIX  Copyright (C) 1988 Yale University \\
;Loading  /usr/local/lib/t/tfix5.t into T-IMPLEMENTATION-ENV \\
T Top level \\
{\tt $>$} (list 'planner 'conniver) \\
(PLANNER CONNIVER) \\
{\tt $>$} \\
\end{codexenv}
The interaction may look slightly different in the other implementations.
The above illustrates the startup sequence, which proceeds as follows:
\begin{itemize}
\item[{}]The user invokes {\bf T} with an appropriate command.

\item[{}]The {\bf T} system identifies itself by giving the processor and
operating system under which it believes itself to be running, the
major and minor system \ix{version numbers}, and the system
edit number.  The version numbers identify which release of
{\bf T} is running.  The edit number is
useful to the system implementors and
should be provided in any bug reports sent to them.

\item[{}]{\bf T} loads a \iix{patch file}, if one exists.  The patch file
consists of forms which fix bugs in the current release of the system.

\item[{}]{\bf T} loads a user \ix{initialization file}, if one exists.  The user
\ix{initialization file} consists of any forms which the users wants to
have evaluated when {\bf T} starts up.  The location in the file system
where the initialization file is found is system-dependent, but is usually
the file {\tt init.t} in the user's home directory.

\item[{}]{\bf T} enters a \iix{read-eval-print loop}.  Read-eval-print loops
are described in section \ref{section:repl}.
\end{itemize}

\index{STOP@{\tt STOP}}
{\mbox {\tt (STOP) $\longrightarrow$\  {\it undefined\/}}}
\hfill  

\begin{inset}{}
Exits {\bf T} in such a way that it may be resumed later.
Control returns to the context from which {\bf T}
was invoked.  Under Unix, this usually means the
shell.  Under VMS, this means the command interpreter (DCL).
{\tt STOP} is not defined in Aegis {\bf T} because
the Aegis environment makes it unnecessary.
\end{inset} 

\index{EXIT@{\tt EXIT}}
{\mbox {\tt (EXIT)}}
\hfill  

\begin{inset}{}
Exits {\bf T}, returning control to the context in which {\bf T}
was invoked in the first place (usually a shell or other command processor).
Any resources associated with the {\bf T} process will be freed;
{\tt EXIT} is not reversible.
A call to {\tt EXIT} cannot return.
\end{inset} 

\index{COMMAND-LINE@{\tt COMMAND-LINE}}
{\mbox {\tt (COMMAND-LINE) $\longrightarrow$\  {\it list\/}}}
\hfill  

\begin{inset}{}
This variable has as its value the command line which
was used to invoke {\bf T}, represented as a list of strings.
\end{inset}

\section{Suspending {\bf T}}


\begin{inset}{Caution:}
The following is somewhat Sun specific.
\end{inset}

A system is suspended as follows:

\begin{codexenv}
\% t -h 8000000 \# as big as possible \\

$>$ ;; load stuff \\
$>$ (gc) \\
$>$ ((*value t-implementation-env 'system-suspend) filespec nil) \\
$>$ (exit)
\end{codexenv}

If a GC occurs during the suspend it will hang.  This means that the heap
was not big enough.

The binary distributions are a directory called ``tsystem''.
In that directory
are a bunch of files including a script called ``linkt'' which takes
a {\tt .o} file produced by suspend and creates an executable.

\begin{codexenv}
\% cd tsystem \\
\% linkt filespec.o newimage
\end{codexenv}

If the code to be loaded before suspending a system contains
{\mbox {\tt DEFINE-FOREIGN}}
forms, files containing these forms should be loaded inside of:

{\tt \begin{tabbing}
(bind \= ((\= (*value t-implementation-env 'make-foreign-procedure)\+ \+ \\
        (*value t-implementation-env 'make-foreign))) \- \\
  (load file1) \\
  \ldots\ )
\end{tabbing}}

In this case, the {\tt linkt} script must be modified to 
{\tt .o} files that are referenced by the {\mbox {\tt DEFINE-FOREIGN}} expressions.

{\bf System building:}

It is possible to build a system from the sources.  The tsystem directory
contains a file, i.e. ``sunbuild.t'' which explains how.

\section{Read-eval-print loops}

\label{section:repl}

The user usually interacts with the {\bf T} system
via a \ix{read-eval-print loop}.
As illustrated above, this is a command loop which repeatedly reads an
expression, evaluates it, and prints the value.

The read-eval-print loop is a simple command processor;
it prints a prompt, reads a command from the terminal,
executes the command, then prints another prompt, ad infinitum.
A \iix{command} is any executable {\bf T} form, and executing
the command consists of evaluating the form and printing the result.


\index{\#\#@{\tt \#\#}}
{\mbox {\tt \#\# $\longrightarrow$\  {\it object\/}}}
\hfill  

\begin{inset}{}
The variable {\tt \#\#} always has as its value the last object
which was {\it printed\/} by the read-eval-print loop, that is, the value
of the last expression typed by the user.
\end{inset}

\index{++@{\tt ++}}
{\mbox {\tt ++ $\longrightarrow$\  {\it object\/}}}
\hfill  

\begin{inset}{}
{\bf Removed in {\bf T3}.}
The variable {\tt ++} always has as its value the last expression
{\it read\/} by the read-eval-print loop.
It is not assigned this value, however, until {\it after\/} the expression
has been evaluated, so that a new expression may refer to
the previous one.
\end{inset} 

Expressions are read from the terminal by applying the {\tt READ}
operation (actually, the value of {\tt (REPL-READ)}; see page
\pageref{REPL-READ}) to the terminal input port.  Initially, that
port's read table is the standard read table, but this may be changed
using {\tt SET}, for example:
\begin{codexenv}
(SET (PORT-READ-TABLE (TERMINAL-INPUT)) *MY-READ-TABLE*)
\end{codexenv}

Evaluation is performed with respect to a particular variable
environment and its syntax table.  The read-eval-print loop may move
from place to place within the environment hierarchy; one may control
the evaluation environment and syntax table by setting {\tt (REPL-ENV)}.

\index{REPL-ENV@{\tt REPL-ENV}}
{\mbox {\tt (REPL-ENV) $\longrightarrow$\  {\it environment\/}}}
\hfill Settable

\begin{inset}{}
Accesses the environment passed to {\tt (REPL-EVAL)} by the
read-eval-print loop.  Initially, this is the scratch environment
(see page \pageref{USER-ENV}).
\end{inset} 

\section{Command levels}


Read-eval-print loops may be invoked recursively.  Each currently running
read-eval-print loop is said to be at a different \iix{command level}.
The initial read-eval-print loop is at {\it top level\/}, and recursive
read-eval-print loops are at successively deeper levels.

The level of the current command loop is reflected in the way the
loop prompts for input.  At top level, the prompt is a single
greater-than sign ({\tt >}).  At deeper command levels, the prompt
contains as many greater-than signs as there are active read-eval-print
loops; for example, {\tt >>>} if there are two recursive read-eval-print
loops beneath the top level one.

Deeper command levels are usually entered as the result of program
execution errors, but may also be entered because of a keyboard
interrupt or an explicit call to {\tt BREAKPOINT}.

{\it Interrupts:\/} \index{interrupts}
Issuing a keyboard interrupt will asynchronously enter a read-eval-print
loop.  One may proceed from this breakpoint, at the point where
computation was interrupted, by doing {\tt (RET)}.  Keyboard interrupts
are normally issued under Aegis by giving a Display Manager {\tt DQ}
command (normally assigned to control-Q), under VMS by typing control-C,
or under Unix by typing the interrupt character (normally control-C
or DEL).

{\it End-of-file:\/} \index{end-of-file} \label{end-of-file}
An end-of-file condition on the terminal input port (see page
\pageref{TERMINAL-INPUT}) which occurs at a read-eval-print loop
will cause control to transfer up one command level to the next
read-eval-print loop.  End-of-file can usually be generated under
Aegis with the display manager {\tt EEF} command (normally assigned
to control-Z), under VMS by typing control-Z, or under Unix by typing
the end of file character (normally control-D).
  
\index{RESET@{\tt RESET}}
{\mbox {\tt (RESET)}}
\hfill  

\label{RESET}
\begin{inset}{}
Transfers control directly to the top-level read-eval-print loop
by performing a throw (see page \pageref{CATCH}).
\end{inset} 

\index{BREAKPOINT@{\tt BREAKPOINT}}
{\mbox {\tt (BREAKPOINT . {\it message\/}) $\longrightarrow$\  {\it object\/} {\rm or} {\it undefined\/}}}
\hfill  

\begin{inset}{}
Enters a read-eval-print loop.  If {\it message\/} is non-null, then it
is printed on {\tt (ERROR-OUTPUT)} using {\tt DISPLAY}.
If {\mbox {\tt (RET {\it object\/})}} is called, then the loop terminates and
{\it object\/} is returned as the value of the call to
{\tt BREAKPOINT}.  If an end-of-file condition occurs, then
control is thrown to the read-eval-print loop at the next higher level,
which continues.
\end{inset} 

\section{Transcripts}


A \iix{transcript} is a record of the user's interaction with the
{\bf T} system.  Transcripts are necessary in {\bf T} implementations
under operating systems which do not natively provide transcript
facilities.  Transcripts are not necessary, for example, when running
under the Aegis Display Manager.

\index{TRANSCRIPT-ON@{\tt TRANSCRIPT-ON}}
{\mbox {\tt (TRANSCRIPT-ON {\it filename\/}) $\longrightarrow$\  {\it undefined\/}}}
\hfill  

\begin{inset}{}
Starts writing a transcript to the specified file.  All output to
{\tt (TERMINAL-OUTPUT)} and input from {\tt (TERMINAL-INPUT)} between
calls to {\tt TRANSCRIPT-ON} and {\tt TRANSCRIPT-OFF} is written to
the file.  A subsequent call to {\tt TRANSCRIPT-OFF} will terminate
the transcript, closing the file.
\end{inset} 

\index{TRANSCRIPT-OFF@{\tt TRANSCRIPT-OFF}}
{\mbox {\tt (TRANSCRIPT-OFF) $\longrightarrow$\  {\it undefined\/}}}
\hfill  

\begin{inset}{}
Closes the active transcript file.
\end{inset} 

\section{Customization}


The various phases of the read-eval-print loop may be customized by
assigning values to switches.

\index{REPL-READ@{\tt REPL-READ}}
{\mbox {\tt (REPL-READ) $\longrightarrow$\  {\it procedure\/}}}
\hfill Settable

\label{REPL-READ}
\begin{inset}{}
Accesses the {\tt READ} part of the read-eval-print loop.  Initially, this is
{\tt READ}.
\end{inset} 

\index{REPL-EVAL@{\tt REPL-EVAL}}
{\mbox {\tt (REPL-EVAL) $\longrightarrow$\  {\it procedure\/}}}
\hfill Settable

\begin{inset}{}
Accesses the {\tt EVAL} part of the read-eval-print loop.  Initially, this is
{\tt EVAL}.
\end{inset} 

\index{REPL-PRINT@{\tt REPL-PRINT}}
{\mbox {\tt (REPL-PRINT) $\longrightarrow$\  {\it procedure\/}}}
\hfill Settable

\begin{inset}{}
Accesses the {\tt PRINT} part of the read-eval-print loop.  Initially, this
is {\tt PRINT}.
\end{inset} 

\index{REPL-PROMPT@{\tt REPL-PROMPT}}
{\mbox {\tt (REPL-PROMPT) $\longrightarrow$\  {\it procedure\/}}}
\hfill Settable

\begin{inset}{}
Accesses the prompting routine used in the read-eval-print loop.  This
should be a procedure of one argument, which is a nonnegative integer
giving the command level (zero at top level, one at the next deeper
level, and so on).  The procedure should return a string.  Initially,
{\tt (REPL-PROMPT)} is a procedure that returns {\tt > } at the top
level, {\tt >> } at the level below that, etc.
\end{inset} 

\index{LOAD-NOISILY?@{\tt LOAD-NOISILY?}}
{\mbox {\tt (LOAD-NOISILY?) $\longrightarrow$\  {\it boolean\/}}}
\hfill Settable

\begin{inset}{}
If {\tt (LOAD-NOISILY?)} is true (which it is initially), then {\tt LOAD}
and {\tt REQUIRE} will print the value of each top-level expression
in the file (standard compiler only).  The output goes to the terminal
output port.
\end{inset} 

\index{REPL-WONT-PRINT?@{\tt REPL-WONT-PRINT?}}
{\mbox {\tt (REPL-WONT-PRINT? {\it object\/}) $\longrightarrow$\  {\it boolean\/}}}
\hfill Operation

\begin{inset}{}
Read-eval-print loops will not print any object which answers true to
this operation.
Note that this is unrelated to the functioning of {\tt PRINT} itself.
\end{inset} 

\index{REPL-WONT-PRINT@{\tt REPL-WONT-PRINT}}
{\mbox {\tt REPL-WONT-PRINT $\longrightarrow$\  {\it object\/}}}
\hfill  

\begin{inset}{}
Its value is an object which answers true to the {\tt REPL-WONT-PRINT?}
predicate.
\begin{codexenv}
REPL-WONT-PRINT  $\equiv$  (OBJECT NIL ((REPL-WONT-PRINT? SELF) T))
\end{codexenv}
\end{inset}
